// ==================================================================================
// Shared Genomics Project MPI Codebase
// Version 1.0 30/04/2010
//
// (c) 2010 University of Manchester all rights reserved
//
// This file is distributed under the GNU General Public License, Version 2.  
// Please see the file COPYING.txt for more details
// ==================================================================================

#ifndef _TYPES_H_
#define _TYPES_H_

/*!
* \mainpage

<h2>Contents</h2>
<ul>
<li><a href="#section_001">Overview</a></li>
<li><a href="#section_002">PLINK Citation</a></li>
<li><a href="#section_003">Copyright Statement</a></li>
<li><a href="#section_004">System Requirements</a></li>
<li><a href="#section_005">Installation</a></li>
<li><a href="#section_0051">Running the Examples</a></li>
<li><a href="#section_006">Modules</a></li>
<li><a href="#section_007">Primary Use Case</a></li>
</ul>

<h3><a name='section_001'>Overview</a></h3>
<p>The Shared Genomics project has developed parallelised statistical applications (MPI/OpenMP) which can analyse
large genomic data-sets containing thousands of Single Nucleotide Polymorphisms (SNP).
The code is based on the popular <a href="http://pngu.mgh.harvard.edu/~purcell/plink/" target="_new">PLINK</a> SNP-analysis program.
Unlike standard <a href="http://pngu.mgh.harvard.edu/~purcell/plink/" target="_new">PLINK</a> which by default runs as a single-core 
application, our version is designed to work with multi-core architectures.
The Shared Genomics computational code is written in C rather than C++ and uses standard pointer arithmetic for fast array indexing.
These factors mean that the Shared Genomics analysis codes are quicker when compared to the 
<a href="http://pngu.mgh.harvard.edu/~purcell/plink/" target="_new">PLINK</a> originals.
A x200 increase in performance was achieved when application code was run on a 100-core computer cluster.
The Shared Genomics codebase was developed using real research data from an asthma & allergy cohort study.
Small data-sets of 400-500 SNPs were used to develop programs for interaction modelling 
and data-sets containing 560K SNPs were used to develop code for single association scans.
The statistical codes were successfully deployed on a 102-core 'Windows HPC Server 2008' cluster hosted at the University of Manchester.
</p>

<p>This project has only implemented a sub-set of algorithms from the PLINK based 
on requirements from collaborators.
The genomic I/O library and example programs however do demonstrate how to implement statistical MPI/OpenMP applications.
The majority of analysis algorithms used in this project are derived 
from <strong><a href="http://pngu.mgh.harvard.edu/~purcell/plink/" target="_new">PLINK</a></strong> v1.05. 
All software implementations of algorithms derived from PLINK were unit-tested against the PLINK source code to ensure numerical consistency 
with the parent application.</p>

<h3><a name='section_002'>PLINK Citation</a></h3>
<pre>
PLINK  	     v1.07
Author:      Shaun Purcell
URL:         http://pngu.mgh.harvard.edu/purcell/plink/

Purcell S, Neale B, Todd-Brown K, Thomas L, Ferreira MAR, 
Bender D, Maller J, Sklar P, de Bakker PIW, Daly MJ & Sham PC (2007) 
PLINK: a toolset for whole-genome association and population-based 
linkage analysis. American Journal of Human Genetics, 81.
</pre>

<h3><a name='section_003'>Copyright Statement</a></h3>
<p><em>Copyright of PLINK rests with Shaun Purcell.</em></p>
<p>The Shared Genomics Project MPI codebase is published in the public domain using the <a href="../COPYING.txt">GNU General Public License v2</a>
and is free for research/academic use.</p>

<h3><a name='section_004'>System Requirements</a></h3>
<p><em>Hardware:</em><br />
The Shared Genomics analysis code will run on a cluster or stand-alone work-stations. 
Example programs use 2 MPI threads, i.e. it assumes that the host system is dual-core.</p>

<p><em>For Windows:</em>
<ul style="margin-top:0px;padding-top:0px;">
 <li><a href="http://www.microsoft.com/downloads/details.aspx?familyid=12887DA1-9410-4A59-B903-693116BFD30E&displaylang=en">Microsoft HPC Pack 2008 SDK</a> <em>(Needed to run Shared Genomics statistical applications with MPI)</em></li>
 <li>Microsoft Visual Studio 2008 - Any Edition <em>(Needed if you wish to compile the source code)</em></li>
</ul>
</p>

<p><em>For Linux:</em><br />
The Shared Genomics analysis code is ANSI C/C++ but the 'Windows.h' library was used to 
provide file copy functions. The code will compile under Linux only if the functions defined 
in copyfile.h are replaced with the standard Linux shell commands.</p>

<h3><a name='section_005'>Installation</a></h3>
<p>
This release of the Shared Genomics Project has only be tested on Windows Vista and Windows 7.
It is not recommended that you try to compile and run these examples on Windows XP as we have
found issues using the latest Microsoft MPI SDK with this operating system.</p>

<ol>
<li>Ensure that you have installed Microsoft HPC Pack 2008 SDK.</li>
<li>Go to <em>Control Panel->System->Advanced Settings</em></li>
<li>Click on the <em>Advanced</em> tab and click on the <em>Environment Variables</em> button.</li>
<li>Find the PATH variable in the list and append <em>C:/Program Files/Microsoft HPC Pack 2008 SDK/bin</em> to the <em>PATH</em> variable by 
using the <em>Edit</em> button.</li>
<li>Inspect the <em>System Variables</em> list and look for the presence of at least 4 environment variables prefixed with CCP. If those variables are 
absent, the Microsoft HPC SDK was not installed correctly. </li>
<li>Click <em>Ok</em> to apply the changes.</li>
<li>If you wish to compile your own executables from source, please ensure that Visual Studio 2008 is installed along with all the 'Language Tools' 
for Visual C++. If you are using the Express version of Visual Studio, you can only build the x32 version of the SharedGenomics.sln solution. </li>
<li>You can try out our programs by downloading either the <a href="http://sharedgenomics.codeplex.com/">release package</a> or 
<a href="http://sharedgenomics.codeplex.com/SourceControl/list/changesets">source code</a> from our site on CodePlex. The following section provides
instructions on how to run our example analysis tests on some mock data.</li>
</ol>

<p>NB Future releases of the HPC SDK may mean that the quoted directory paths and shell variables may have changed.</p>

<h3><a name="section_0051">Running the Examples<a></h3>
<p><em>From our downloadable release package:</em>
<ol>
<li>When you unzip the file, make sure you choose to 'Extract All' to a folder on your workstation.</li>
<li>Open the test folder.</li>
<li>Either launch 'run_x32_tests.bat' or 'run_x64_tests.bat' to the test the 32 and 64 bits respectively.</li>
<li>For each program tested, the outputs will be saved to the 'test' folder. Please note an example of the syntax needed to run the statistical 
programs is given in the command console window.</li>
</ol>
<em>From our downloadable source code:</em>
<ol>
<li>When you unzip the file, make sure you choose to 'Extract All' to a folder on your workstation.</li>
<li>Open the Solution File 'SharedGenomics.sln' in Visual Studio 2008.</li>
<li>Use 'Configuration Manager' in Visual Studio to specify a particular 'x32/x64, Debug/Release' release and click 'Build Solution'.</li>
<li>Open a command console window and change the directory to the working folder within the source code.</li>
<li>Either launch 'run_x32_debug.bat', 'run_x32_release.bat', 'run_x64_debug.bat' or 'run_x64_release.bat' to the test the 32/64bit debug/release
builds respectively.</li>
<li>For each program tested, the outputs will be saved to the 'working' folder. Please note an example of the syntax needed 
to run the statistical programs is given in the command console window.</li>
</ol>
</p>
<p>NB The example datasets are kept in the 'data' folder and the rs numbers of SNPs are valid and are derived from the NCBI SNP database. The 
genomic data and participant identifies are all fake.</p>

<h3><a name='section_006'>Modules</a></h3>
<ul>
 <li><a href="./group__pmaths.htm">Pmaths Utility Library</a></li>
 <li><a href="./group__mpi__stats.htm">Statistical Programs - MPI</a></li>
 <li><a href="./group__gio.htm">Genomic I/O Library</a></li>
 <li><a href="./group__examples.htm">Examples</a></li>
</ul>

<h3><a name='section_007'>Primary Use Case</a></h3>
<p>The primary use case which was used to design the MPI program of the Shared Genomics Projects is as follows:-</p>
<em>
<p>
The genomic dataset awaiting analysis resides on a cluster infra-structure.
A user's genomic dataset consists of a PLINK compatible MAP file (SNP list), PED file (Genomic Data) and PHE file (list of phenotype).
These files are in a text file format. An individual in the dataset is associated with phenotypes and SNPs by a unique personal identifier.
The genomic data starts as an Individual major dataset. The files of a dataset share a common file-stem and are kept in a particular remote directory
on the central file system.
</p>
<p>
The cluster consists of a central file system and a number of processing nodes connected by a fast network. 
Each processor node has is own local file system and disk.
The central file system stores the original dataset and any final output from the statistical analysis programs.
The processing nodes perform statistical calculations, reading input data from a remote directory on the central file system.
Output data is written to file locally on a processor node, then copied to the remote directory on the central file system for later integration 
and parsing.
</p>
<p>
Each processor node has a unique identifying number.
When a job is sent to the processor nodes, each job is given a unique identifier. 
The output file generated by a processing node is a concatenation of the job ID and processor number.
Communication between the central file system and a processor node is kept to a minimum. 
If a processor node fails while performing a section of a statistical calculation,
that section of the calculation can be repeated on another core assuming the identity of the failed core.
</p>
</em>

*/

/*!
 * \file
 * \ingroup pmaths
 * \brief	Basic data-types used by the statistical analysis programs.
 * \details Header file defines the base-types used by the statistical analysis programs.
 *			All of the types defined utilise standard ANSI datatypes. These values are only
 *          defined to maintain naming conventions used in the PLINK C++ application.
 */
#ifdef __cplusplus
extern "C" {
#endif

/*!
\brief		Simple 1-Byte boolean
\details	Equivalent to the C++ BOOL data-type.
			The MPI-code is normally compiled as ANSI 'C' which does 
			not have a BOOL typedef.
 */
typedef unsigned char BOOL;

/*!
\brief		A Vector datatype
\details	A vector data type, a.k.a 1-D double array.
*/
typedef double* VECTOR_T;

/*!
\brief		A Matrix data-type
\details	A matrix data-type representing a 2-D array of doubles.
\sa			See also create_matrix,
*/
typedef double** MATRIX_T;

/*!
\brief Boolean TRUE
*/
#define TRUE 1

/*!
\brief Boolean FALSE
*/
#define FALSE 0

/*!
\brief The number of bits assigned to byte for the target architecture.
*/
#define BITS_PER_BYTE 8

#ifdef __cplusplus
}
#endif

#endif
